Btw if you think it's beneficial, feel free to request my review for any IDOM PRs.

Here's the beta for the new react docs: https://beta.reactjs.org/

After doing a bunch of development with IDOM today, here's some readability suggestions for IDOM docs code snippets:

• Directly use the VDOM tag functions (div(...), span(...), etc) in all examples (strip out idom.html., and add an from idom.html import div, ...)
• If an HTML attribute dict spans more than one line and doesn't need to be dynamic, define it as a constant (ex. SNAKE_ATTR = {"className":"foo", ...})
  • Too many attributes embedded within the VDOM template severely impacts readability
  • Use a generator function for long attribute dicts that need to be dynamic
• Functional components should follow PEP8 and use snake_case. We aren't in JS, and it feels silly to mimic JS naming conventions within Python PEP8.

Functional components should follow PEP8 and use snake_case

This isn't made clear in the docs anywhere, but I use "title-case" for those functions because that's how I identify that those functions define a component. With that convention, flake8-idom-hooks is able to enforce the rules of hooks by only looking in the bodies of title-cased functions for hook usages.

Using title case isn't actually the convention in JS either. Only component functions have title-cased names when developing with React and this fact is leveraged in the same way into a linter.

@Archmonger I think the doc rewrite is going really well. Here's a build of the docs as of writing this: build.zip

Hopefully you can use that to do a bit of review.

So the docs I'd written on hooks thus far were more like API docs. They jump right into the finer details of how the hooks work. As a result, I put them in the "Reference Material" section under "Hooks API". The broader plan is to progressively introduce hooks in the "Adding Interactivity" and "Managing State" sections through narratively driven explanations. The first place a reader would see a hook is under "Adding Interactivity" and "Components With State".

@Archmonger here's the next build. At this point I've covered everything that the current docs do and more. I plan to mark which sections are still under construction, but in general I think this is really close to being ready to merge: build.zip
.

I'll review this weekend.

nox -s docs results in

    [16:46:30] [snowpack] ! building files...
    [16:46:30] [snowpack] Build Result Error: There was a problem with a file build result.
    [16:46:30] [snowpack] Package "idom-app-react" not found. Have you installed it?
    [16:46:30] [snowpack] Error: Package "idom-app-react" not found. Have you installed it?

I think you might need to update your version of NPM: npm install -g [email protected]

Shoot. Never mind, I broke something in that last commit. I also amended the commit so that might prevent a simple git pull 😬.

Currently working on my review, not sure if the force push breaks that though.

Should be ok. It was a minor fix.

@Archmonger I think I'm going to merge this. We can make incremental improvements from there.

I'll leave the residual review on this PR so we'll know what needs to get done on the incremental updates.